docs(calculate): add JSDoc for streak and montly stats calculation (JhaSourav07#472)

## Description
Fixes JhaSourav07#303 

Added comprehensive JSDoc documentation in `lib/calculate.ts`.

Changes included:
 - Added complete `@param` documentation for function parameters
 - Documented parameter types and default values
 - Added explanation for timezone handling and `now` override behavior
 - Documented the one-day grace-period logic used in streak calculations
- Added usage examples showing timezone override and custom date
injection
 - Added documentation for monthly statistics calculation

No functional logic was changed. This PR only improves maintainability
and onboarding for new contributors.

## Pillar

* [ ] 🎨 Pillar 1 — New Theme Design
* [ ] 📐 Pillar 2 — Geometric SVG Improvement
* [ ] 🕐 Pillar 3 — Timezone Logic Optimization
* [x] 🛠️ Other (Bug fix, refactoring, docs)

## Visual Preview

N/A — Documentation-only change

## Checklist before requesting a review:

* [x] I have read the `CONTRIBUTING.md` file.
* [x] I have tested these changes locally
(`localhost:3000/api/streak?user=YOUR_USERNAME`).
* [x] I have run `npm run format` and `npm run lint` locally and
resolved all errors (CI will fail otherwise).
* [x] My commits follow the Conventional Commits format (e.g.,
`feat(themes): ...`, `fix(calculate): ...`).
* [ ] I have updated `README.md` if I added a new theme or URL
parameter.
* [x] I have started the repo.
* [x] I have made sure that I have only one commit to merge in this PR.
* [x] The SVG output matches the CommitPulse "premium quality" aesthetic
standard (no raw elements, smooth animations, correct fonts).
* [ ] (Recommended) I joined the CommitPulse Discord community for
contributor discussions, mentorship, and faster PR support.

Author: JhaSourav07

lib/calculate.ts

@@ -1,6 +1,56 @@
 // lib/calculate.ts
 import type { ContributionCalendar, StreakStats, MonthlyStats } from '../types';
 
+/*
+Calculates streak statistics from a GitHub contribution calendar.
+
+This function computes:
+- Current streak length (with a one-day grace period)
+- Longest streak length across the calendar
+- Total contributions made
+- Effective "today" date used for UI display
+
+Current Streak Logic:
+The streak remains active if there are no contributions today
+but there were contributions yesterday. This prevents streaks
+from breaking prematurely due to timezone differences.
+
+Timezone Handling:
+Contribution dates are calendar-based. The provided IANA timezone
+determines what "today" means for the user, ensuring streaks are
+calculated correctly in local time (e.g., "Asia/Kolkata",
+"America/Los_Angeles"). Defaults to "UTC".
+
+@param {ContributionCalendar} calendar
+  GitHub contribution calendar data containing weekly entries.
+
+@param {string} [timezone='UTC']
+  IANA timezone string used to determine the local date.
+
+@param {Date} [now=new Date()]
+  Current time reference for calculations. Useful for testing
+  or overriding the system clock.
+
+@returns {StreakStats}
+  An object with:
+  - currentStreak: active streak length
+  - longestStreak: longest historical streak
+  - totalContributions: total contribution count
+  - todayDate: effective date used for streak/UI calculations
+
+@example
+// Calculate streak stats using a specific timezone
+const stats = calculateStreak(calendar, 'Asia/Kolkata');
+
+@example
+// Override both timezone and current time (useful in tests)
+const stats = calculateStreak(
+  calendar,
+  'America/Los_Angeles',
+  new Date('2026-05-25T10:00:00Z')
+);
+*/
+
 export function calculateStreak(
   calendar: ContributionCalendar,
   timezone: string = 'UTC',
@@ -77,6 +127,34 @@ export function calculateStreak(
   };
 }
 
+/*
+  Calculates monthly contribution statistics from a GitHub contribution calendar.
+
+  Figures out how many contributions were made this month and last month, then compares them.
+
+  @param {ContributionCalendar} calendar
+    Weekly GitHub contribution data.
+
+ @param {string} [timezone='UTC']
+    Timezone to decide which month is "current".
+    Example: 'Asia/Kolkata' ensures local month is used.
+
+  @param {Date} [now=new Date()]
+    Current date/time reference (useful for testing).
+
+  @returns {MonthlyStats}
+   - currentMonthTotal: contributions this month
+   - previousMonthTotal: contributions last month
+   - deltaAbsolute: difference (this − last)
+   - deltaPercentage: % change, rounded
+   - currentMonthName: name of this month (e.g. "May")
+
+  @example
+  const stats = calculateMonthlyStats(calendar, 'Asia/Kolkata');
+  stats.currentMonthName → "May"
+  stats.deltaPercentage → 42
+*/
+
 export function calculateMonthlyStats(
   calendar: ContributionCalendar,
   timezone: string = 'UTC',