Replace flowchart/ with a traceable specification in docs/

The two Mermaid diagrams under flowchart/ described the intended flow but
had drifted from the code and carried no link back to it. docs/ now holds
the specification instead: 15 Italian documents (flows, architecture, data
model, API, security, audit log, operations, decisions and limits, bug
history) with 472 numbered requirements, each pointing at the function
that implements it and the test that covers it. docs/processo-di-modifica.md
defines the ID convention and the spec -> code -> test change workflow, and
CLAUDE.md now names docs/ as authoritative.

Writing the spec from the code also corrected stale claims in CLAUDE.md
(B-41's get_history check, BUGS.md still tracking B-71/B-72, Cache-Control
scope, the error contract's bare-string exceptions) and in the operator
guides (payouts do retry, only `drawing` fails to resume, rounds do not
open without fee_address). The B-70 doc test now pins the prose in
docs/scommesse-e-prelievi.md instead of the deleted diagram.

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

app/rounds/draw.py

@@ -78,9 +78,9 @@ def header_meets_its_own_target(header_hex: str) -> bool:
 
 
 def draw_winner(participants: list[str], block_hash_hex: str) -> str:
-    """v1 draw algorithm (flowchart.mmd, node R): seed = block hash as an integer,
-    index = seed mod participant_count, winner = participants[index]. Anyone can
-    recompute and verify it from public data. Deliberately simple/replaceable."""
+    """v1 draw algorithm (docs/ciclo-di-vita-del-round.md): seed = block hash as an
+    integer, index = seed mod participant_count, winner = participants[index]. Anyone
+    can recompute and verify it from public data. Deliberately simple/replaceable."""
     if not participants:
         raise ValueError("no participants to draw from")
     seed = int(block_hash_hex, 16)

app/rounds/scheduler.py

@@ -39,10 +39,10 @@ _DRAW_STALL_THRESHOLD_SECONDS = 360  # a few multiples of PLM's 120s block time
 
 
 class RoundScheduler:
-    """Background task implementing flowchart.mmd's DRAW subgraph: closes the
-    round on its timer (once any in-flight bets have confirmed), draws a winner
-    from the next confirmed block, and broadcasts the payout. The next round only
-    opens once this one is fully closed (rounds/service.get_active_round)."""
+    """Background task implementing the round lifecycle (docs/ciclo-di-vita-del-round.md):
+    closes the round on its timer (once any in-flight bets have confirmed), draws a
+    winner from the next confirmed block, and broadcasts the payout. The next round
+    only opens once this one is fully closed (rounds/service.get_active_round)."""
 
     def __init__(self, session_factory: async_sessionmaker, listener: ElectrumListener):
         self._session_factory = session_factory

app/wallet/hd.py

@@ -51,7 +51,7 @@ def derive_user_wif(derivation_index: int) -> str:
 
 
 def derive_pool_key() -> HDKey:
-    """The "indirizzo padre" from the flowchart: all bets are sent here, and
+    """The pool key ("indirizzo padre"): all bets are sent here, and
     payouts are signed with this key. Reserved on branch 1 of the account (branch 0
     is user addresses), index 0 — not a spec requirement, an implementation choice
     to keep it in the same encrypted master key rather than a separate secret."""