Regarding the spirit world vs the real world.
First off, the spirit world isn't the same as the afterlife, so while Iroh is a spirit, it's not guaranteed that every human spirit will go there.
It's important to note that aang, jinora, korra and zaheer "phase" into the spirit world.
First they leave their bodies as spirits and then they transition to the spirit world.
When they leave their body to become spirits, the body is vulnerable and needs protection.
That is the most important part of the process for humans because while they can go to the spirit world as spirits, they generally cannot interact with the real world as disembodied spirits so they can only go to the spirit world or in Jinora's case scout around.
If you walk into the spirit world via the portals, because you have your body you can bend, but if you project then you can't.
Unfortunately the really janky aspects of this are related to all this astral projection stuff since it implies that spirits should be able to freely phase into the physical world anyways, even if they too have to subscribe to the inability to affect the physical world without a body.
Regarding Zaheer in jail:
He astrally projects into the spirit world and could conceivably travel within the spirit world to the portals and wall out, but I guess we have to assume once he did, he'd be back in astral projection form.
As for Iroh...
There are some janky implications here. Since the only physical barrier between the spirit world and physical world is the sealed portals (except for that one time Wanshitong the spirit owl sank his library into the spirit world) the implication for Iroh's journey to the spirit world would've had to have been meditative.
So if Iroh can meditate into the spirit world, I guess the explanation for him still being there would be that he chose to meditate into the spirit world and let his physical body die... except as a spirit you're immortal...?