docs(log): document totalBalanceChf semantics and guardrails

[TaprootFreak]

Summary

Adds documentation (comments only, no behavior change) explaining how to read totalBalanceChf in the FinancialDataLog, so future contributors and agents interpret balance movements correctly — both from the code and from the db-debug script.

• JSDoc on the BalancesTotal interface (log.dto.ts) describing the invariant and the only three drivers of a total-balance change.
• A short pointer comment at the computation site in LogJobService.
• A self-contained semantics + safety block in scripts/db-debug.sh, so an agent using --balance / --anomalies / --stats understands the numbers without reading the source.

Why

totalBalanceChf = plusBalanceChf - minusBalanceChf. Customer flow is balance-neutral: a deposit raises plus AND minus equally, and completing the order lowers both again, leaving only the fee. So the total is effectively the operating equity of the flow business and only moves due to:

1. operating profit / fees (gradual, positive, realised on order completion)
2. FX — plus and minus are different asset baskets, so their CHF marks drift independently while orders are open (the normal intraday noise)
3. an error or a realised loss (a discrete, persisting step)

This clarifies why the two existing guardrails exist: the valid: false flag on jumps beyond Config.financeLogTotalBalanceChangeLimit, and the minTotalBalanceChf safety-mode floor. A sudden (especially negative) step is suspicious rather than customer activity.

Test plan

• npm run format:check
• npm run lint
• npm run type-check
• bash -n scripts/db-debug.sh
• Comments only — no runtime change.