Document Monero RPC get_transfers unlocked field defect

- Add comprehensive documentation of RPC inconsistency
- Include symptoms, impact, workarounds, and references
- Establishes framework for documenting future Monero RPC issues

docs/MONERO_DEFECTS.rst

@@ -0,0 +1,57 @@
+=====================
+Monero RPC Defects
+=====================
+
+This document catalogues known defects and inconsistencies in the Monero wallet RPC that affect payment processing.
+
+Known Defects
+=============
+
+1. get_transfers "unlocked" Field Inconsistency
+-----------------------------------------------
+
+**Issue**: The ``get_transfers`` RPC method returns individual transfers with ``unlocked: false`` even when those transfers have >10 confirmations and the account's ``get_balance`` shows positive unlocked balance.
+
+**Symptoms**:
+- ``get_balance`` returns positive ``unlocked_balance`` for account
+- ``get_transfers`` shows same transfers with ``unlocked: false`` 
+- Transfers have sufficient confirmations (17-20+ blocks)
+- ``sweep_single`` fails with "failed to parse key image" error
+
+**Impact**: 
+- Prevents reliable detection of spendable outputs per subaddress
+- Breaks subaddress-isolated sweep functionality
+- Forces reliance on account-level balance instead of transfer-level status
+
+**Workaround**: 
+Ignore the ``unlocked`` field in ``get_transfers`` responses and rely on account-level ``unlocked_balance`` from ``get_balance`` when the discrepancy occurs.
+
+**Example Log**::
+
+    DEBUG: Transfer 0: subaddr={'major': 0, 'minor': 20}, amount=3537607425, unlocked=False
+    DEBUG: Transfer 1: subaddr={'major': 0, 'minor': 19}, amount=6976160352, unlocked=False
+    Transfer: amount=6976160352, confirmations=20, unlocked=False
+    Account 0 unlocked balance: 0.010513767777 XMR
+
+**Date Observed**: September 2025
+**Monero Version**: Unknown (observed via monero-wallet-rpc)
+
+References
+==========
+
+Related GitHub issues in monero-project/monero repository:
+- #4500: get_transfers omits transactions when sending to/from same account  
+- #8613: RPC wallet shows wrong balance
+- #5106: get_transfers pending transfer toggling issue
+- #2820: "Not enough money in unlocked balance" errors
+
+Contributing
+============
+
+When documenting new defects, include:
+1. Clear description of incorrect behavior
+2. Expected vs actual behavior  
+3. Reproduction steps
+4. Impact on payment processing
+5. Implemented workarounds
+6. Date observed and Monero version if known