docs: documenta i contratti di inspect paths e schema-diff

[Gabrymi93]

Closes #52

Summary

• Documenta il contratto operativo di inspect paths e inspect schema-diff, chiarendo quando usare ciascuno e cosa garantisce --json
• Corregge il payload documentato rispetto all'output reale: suggested_read_path / suggested_read_exists (non suggested_read.yml), aggiunge decimal, espande paths.raw|clean|mart come blocchi annidati con subkey esplicite, aggiunge primary_output_file e warnings a raw_hints
• Aggiunge guidance sui casi d'uso per CI, notebook e dataset multi-anno

Changes

• README.md: nuova sezione inspect paths vs inspect schema-diff con contratti, guidance su --json e regole pratiche
• docs/notebook-contract.md: nuove sezioni per il contratto di inspect paths e la differenza rispetto a inspect schema-diff

Test plan

• Cambio solo docs — nessuna modifica a runtime o CLI
• Campi del payload verificati contro toolkit/cli/cmd_inspect.py (_payload_for_year, _raw_schema_payload)

🤖 Generated with Claude Code

[matteocavo]

Controllata. Per me questa è ok da mergiare.

Ho verificato il testo nuovo contro l'implementazione attuale di inspect e la documentazione è allineata bene:

• il payload di inspect paths --json è descritto con i campi giusti;
• la distinzione rispetto a inspect schema-diff è chiara;
• la guidance per notebook / CI / fonti multi-anno è utile e non sovrapromette.

Non vedo finding bloccanti.