docs: add professional docstrings and inline comments to all source files

[stedrew]

Closes #6.

Summary

• Added Google-style module docstrings, function/method docstrings, and targeted inline comments to all 14 Python source files
• No logic changes — purely additive documentation
• replay.py used as the style reference (it was the only file with partial docs); all others brought up to the same standard

What was added per file

File	Key additions
agent_state.py	Module docstring explaining all psychological profile params; AgentRuntimeState field docs; docstrings for all functions
belief_model.py	Module docstring explaining Bayesian pipeline; threshold rationale on categorize_hazard_state; formula explanations on all functions
departure_model.py	Module docstring explaining three departure clauses; inline comments on each clause with motivation
information_model.py	Module docstring; docs on Gaussian noise model and keyword-vote social signal; explanation of keyword priority ordering
routing_utility.py	Module docstring explaining utility formula; rationale for all hardcoded weights (0.8, 1.6, 0.6, 0.75, 8.0); penalty lookup table docs
scenarios.py	Module docstring explaining three information regimes; docs on each config field and what gets stripped per regime
forecast_layer.py	Module docstring; margin band threshold explanations; docs on fire growth metric derivation
metrics.py	Module docstring explaining five KPIs and their calibration purpose; class docstring; docstrings on all methods
replay.py	Module docstring clarifying record/replay contract and output files; expanded method docstrings
calibration.py	Module docstring explaining loss formula, METRIC_SPECS weights and their rationale; docstrings on all functions
experiments.py	Module docstring explaining parameter axes and output files; docstrings on grid/sweep/export functions
study_runner.py	Module docstring explaining three-stage flow and output artifacts; run_study docstring
Spawn_Events.py	Module docstring explaining tuple format and why the large block is commented out
Traci_GPT2.py	Module docstring with full CLI/env-var reference and pipeline overview; fire dynamics section header with constant explanations; docstrings for LiveEventStream, WebDashboard, AgentOverlayManager, AgentMessagingBus, process_pending_departures, process_vehicles, active_fires, compute_edge_risk_for_fires, update_fire_shapes, _circle_polygon, and CLI helpers

Test plan

• Verify no Python syntax errors: python -c "import ast; ast.parse(open('Traci_GPT2.py').read())" passes for all modified files
• Confirm no logic changes via git diff main --stat (only line counts changed, no functional edits)
• Review docstring accuracy against existing code logic in key files (belief_model.py, routing_utility.py, departure_model.py)

🤖 Generated with Claude Code