Document BQL limitations and add reference comments

Added detailed comments to BQL methods explaining:
- Current limitation: cannot access posting metadata (sats-equivalent)
- BQL only queries position amounts (EUR/USD)
- Manual aggregation with caching remains the recommended approach
- Future consideration if ledger format changes

Changes:
- query_bql(): Added limitation warning and future consideration note
- get_user_balance_bql(): Added "NOT CURRENTLY USED" warning
- get_all_user_balances_bql(): Added "NOT CURRENTLY USED" warning

All methods kept as reference code for future architectural changes.

See: misc-docs/BQL-BALANCE-QUERIES.md for complete analysis.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

fava_client.py

@@ -498,6 +498,15 @@ class FavaClient:
         This is a general-purpose method for executing BQL queries against Fava/Beancount.
         Use this for efficient aggregations, filtering, and data retrieval.
 
+        ⚠️ LIMITATION: BQL can only query position amounts and transaction-level data.
+        It CANNOT access posting metadata (like 'sats-equivalent'). For Castle's current
+        ledger format where SATS are stored in metadata, manual aggregation is required.
+
+        See: misc-docs/BQL-BALANCE-QUERIES.md for detailed analysis and test results.
+
+        FUTURE CONSIDERATION: If Castle's ledger format changes to use SATS as position
+        amounts (instead of metadata), BQL could provide significant performance benefits.
+
         Args:
             query_string: BQL query (e.g., "SELECT account, sum(position) WHERE account ~ 'User-abc'")
 
@@ -550,22 +559,33 @@ class FavaClient:
         """
         Get user balance using BQL (efficient, replaces 115-line manual aggregation).
 
+        ⚠️ NOT CURRENTLY USED: This method cannot access SATS balances stored in posting
+        metadata. It only queries position amounts (EUR/USD). For Castle's current ledger
+        format, use get_user_balance() instead (manual aggregation with caching).
+
         This method uses Beancount Query Language for server-side filtering and aggregation,
-        resulting in 5-10x performance improvement over manual aggregation.
+        which would provide 5-10x performance improvement IF SATS were stored as position
+        amounts instead of metadata.
+
+        FUTURE CONSIDERATION: If Castle's ledger format changes to store SATS as position
+        amounts (e.g., "100000 SATS {100.00 EUR}"), this method would become feasible and
+        provide significant performance benefits.
+
+        See: misc-docs/BQL-BALANCE-QUERIES.md for detailed test results and analysis.
 
         Args:
             user_id: User ID
 
         Returns:
             {
-                "balance": int (sats),
+                "balance": int (sats),  # Currently returns 0 (cannot access metadata)
-                "fiat_balances": {"EUR": Decimal("100.50"), ...},
+                "fiat_balances": {"EUR": Decimal("100.50"), ...},  # Works correctly
                 "accounts": [{"account": "...", "sats": 150000}, ...]
             }
 
         Example:
             balance = await fava.get_user_balance_bql("af983632")
-            print(f"Balance: {balance['balance']} sats")
+            print(f"Balance: {balance['balance']} sats")  # Will be 0 with current ledger format
         """
         from decimal import Decimal
         import re
@@ -647,15 +667,25 @@ class FavaClient:
         """
         Get balances for all users using BQL (efficient admin view).
 
+        ⚠️ NOT CURRENTLY USED: This method cannot access SATS balances stored in posting
+        metadata. It only queries position amounts (EUR/USD). For Castle's current ledger
+        format, use get_all_user_balances() instead (manual aggregation with caching).
+
         This method uses Beancount Query Language to query all user balances
-        in a single efficient query, instead of fetching all entries and manually aggregating.
+        in a single efficient query, which would be faster than fetching all entries IF
+        SATS were stored as position amounts instead of metadata.
+
+        FUTURE CONSIDERATION: If Castle's ledger format changes to store SATS as position
+        amounts, this method would provide significant performance benefits for admin views.
+
+        See: misc-docs/BQL-BALANCE-QUERIES.md for detailed test results and analysis.
 
         Returns:
             [
                 {
                     "user_id": "abc123",
-                    "balance": 100000,
+                    "balance": 100000,  # Currently 0 (cannot access metadata)
-                    "fiat_balances": {"EUR": Decimal("100.50")},
+                    "fiat_balances": {"EUR": Decimal("100.50")},  # Works correctly
                     "accounts": [{"account": "...", "sats": 150000}, ...]
                 },
                 ...
@@ -664,7 +694,7 @@ class FavaClient:
         Example:
             all_balances = await fava.get_all_user_balances_bql()
             for user in all_balances:
-                print(f"{user['user_id']}: {user['balance']} sats")
+                print(f"{user['user_id']}: {user['balance']} sats")  # Will be 0 with current format
         """
         from decimal import Decimal
         import re