Streamline README and reorganize async documentation

[Mattsface]

Parent: #297
Depends on: #303

Goal

Make the README easier for new users to scan while documenting the new async client clearly and moving deeper reference material into dedicated docs.

README focus

Keep the README centered on:

• Installation
• Python support
• Basic synchronous usage
• Basic asynchronous usage
• Common error handling
• Links to deeper documentation
• Contribution/project links

Documentation cleanup

Move or consolidate deeper material where appropriate:

• HTTP transport behavior
• Retry policy
• Timeout behavior
• Session/client ownership
• Exception details
• Compatibility mode
• Public API contract
• Advanced usage
• Migration/release-specific information

Contract documentation from #298

Dedicated async documentation must accurately describe the implemented v1.1 contract, including:

Public API and installation

• AsyncMlb and AsyncMlbDataAdapter as supported public async APIs
• Installing async support through the optional async extra
• The initial supported endpoint set and any endpoints still unsupported
• Existing synchronous Mlb usage remains unchanged

Lifecycle and ownership

• async with AsyncMlb() usage
• explicit await mlb.aclose()
• idempotent cleanup behavior
• library-owned vs caller-injected async clients
• caller-injected clients are not closed or silently reconfigured
• callers must finish in-flight operations before closing the client

HTTP and exceptions

Document the public behavior clearly:

2xx                         -> normal decode / parsing
404                         -> endpoint-specific empty behavior
non-404 4xx + strict=True   -> MlbHttpError
non-404 4xx + strict=False  -> MlbHttpCompatibilityWarning + empty behavior
5xx                         -> MlbHttpError
timeout                     -> MlbTimeoutError
transport failure           -> MlbTransportError
invalid successful JSON     -> MlbDecodeError
caller cancellation         -> asyncio.CancelledError

• Explain that async transport-library exception types are not the public API
• Keep compatibility-mode wording aligned with Document a removal timeline for strict_http=False compatibility mode #309 and the eventual documented deprecation/removal policy

Retry and timeout behavior

• Same public timeout input shape/defaults as sync
• Library-owned retry behavior and retryable statuses
• Retry-After behavior
• Retry/backoff is asynchronous/non-blocking
• Caller-injected transport configuration remains caller-controlled

Concurrency

Document the model explicitly:

• One AsyncMlb instance can support multiple concurrent in-flight requests on the same event loop
• Concurrency is caller-controlled using normal asyncio orchestration
• Endpoint methods do not introduce hidden fan-out/background work
• Cancellation/error behavior remains independent unless caller orchestration deliberately couples tasks
• Cross-thread and cross-event-loop use are not promised for v1.1

Include at least one simple concurrent usage example after the basic sequential async quick start.

User-Agent

Document only if appropriate for the transport reference:

• library-owned sync and async clients identify as python-mlb-statsapi/<installed-version>
• caller-injected clients retain caller-controlled headers

Constraints

• Preserve useful technical detail rather than deleting it
• Do not document async methods that are not actually supported
• Keep historical release notes historically accurate
• Do not expose private transport implementation details as stable API
• Documentation must match tested behavior, not planned-but-unimplemented behavior

Acceptance criteria

• README is shorter and easier to navigate
• Sync quick-start remains clear
• Async quick-start is included
• Detailed transport/reference content has a clear home
• Async endpoint support is represented accurately
• Lifecycle and caller-owned-client rules from Define the v1.1 async API and transport contract #298 are documented
• HTTP/error/compatibility decision table is documented accurately
• Cancellation and concurrency behavior are documented
• Retry/timeout behavior is documented without exposing unnecessary transport internals
• Documentation examples are tested or validated where practical

Refs #297
Contract: #298
Compatibility lifecycle: #309