Add comprehensive documentation for modernized metrics system

[lavocatt]

Description

Document the modernized metrics system and create migration guides.

🎯 Why This Matters

Good documentation helps future developers understand the system, reduces onboarding time, and makes maintenance easier.

📝 Step-by-Step Instructions

Step 1: Add JSDoc comments

Add JSDoc comments to all public functions. Example:

/**
 * Converts a duration in milliseconds to a Prometheus time duration string
 * @param ms - Time duration in milliseconds
 * @returns The duration converted to a Prometheus time duration string (e.g., "1m 5s")
 * @example
 * formatPrometheusDuration(65000) // Returns "1m 5s"
 */
export const formatPrometheusDuration = (ms: number): string => {
  // ... implementation
}

Step 2: Create migration guide

Create docs/METRICS_MIGRATION.md with:

• What changed and why
• Before/after code examples
• Common patterns to avoid
• Performance improvements gained

Step 3: Document architecture

Create src/brokers/broker-details/components/Overview/Metrics/README.md with:

• System overview
• Component hierarchy
• Data flow
• How to add new metrics

Step 4: Add usage examples

Document common use cases:

• How to add a new chart type
• How to modify time ranges
• How to handle errors

🧪 What Good Documentation Looks Like

• Clear, concise explanations
• Code examples for complex concepts
• Troubleshooting section
• Links to relevant external docs

Acceptance Criteria

• JSDoc comments on all public functions
• Migration guide created
• Architecture documentation
• Usage examples provided
• Troubleshooting guide included