docs: add Mermaid architecture, flow, and lifecycle diagrams

[christiangda]

What

Adds Mermaid diagrams (which GitHub renders natively) to the README and the token-bucket guide so the design of the library reads at a glance.

README — new Architecture section

• Component flowchart — how BucketLimiter wires together the newLimiter factory, the pluggable Storage[K, Limiter], the per-key access map, and the background sweepLoop, with each key pointing at its own independent golang.org/x/time/rate bucket.
• Sequence diagram — a GetOrAdd(key).Allow() call, including the atomic LoadOrStore race path and the allowed/limited (429) branch.

docs/TOKEN_BUCKET.md

• Token-bucket flow diagram — refill, overflow, and the tokens ≥ 1? decision (complements the existing ASCII art).
• Lifecycle state diagram — a single key moving Absent → Active → Idle → evicted, plus Remove and timer-refresh transitions.
• HTTP-middleware sequence diagram — mirrors the real ReserveN(now, 1) / DelayFrom(now) / Cancel() flow in examples/middleware, showing the 200 vs 429 + Retry-After branches.

Notes

• Docs-only change; no source or public API touched.
• Diagram labels were checked against the actual code (bucket_limiter.go, examples/middleware/main.go) so they stay accurate.
• There was no Go Report Card badge in the README to remove — the current badges are Go Reference, go-mod version, license, Release, and CodeQL. Nothing was changed in the badge row.

🤖 Generated with Claude Code